RESTful Engine Error Handling

The RESTful API includes a facility for collecting and displaying warnings and errors that occur while it is generating output. This article describes what the verify and error handling features do, with some examples of the warnings and errors they capture.

This article also describes the TrackErrors node used in the Engine POST request to enable error handling, and provides an example XML POST request.

Functionality#

The verify feature provides you with actionable information on non-fatal errors, warnings, and other issues contained within a Report Template that occur when generating output with Report Engine for RESTful.

Error handling is a Tag property that can be set to catch errors and exceptions that occur in a Tag's query. Depending on the error-handling Tag property setting, otherwise fatal errors can be captured and ignored so output can be completed despite the error.

Example Warnings and Errors#

Here are some examples of the warnings and errors captured when the verify and error handling features are used:

Data Type Issues#

warning: ‘Buchanan’ is String while NUMBER expected: <wr:out select=’SELECT dbo.Emplayees.LastName FROM dbo.Employees’ type=’NUMBER’ nickname='TypeError’ error-handling=‘Ignore type error;lgnore formatting error;Ignore select error;Node must exist’ datasource=’MSSQL’/>

warning: ‘Buchanan’ is String while NUMBER expected: <wrout select=’SELECT dbo.Emplayees.LastName FROM dbo.Employees’ type=‘NUMBER’ nickname='TypeError’ error-handling=‘Ignore type error;lgnore formatting error;Ignore select error;Node must exist’ datasource=’MSSQL’/>

Formatting Issues#

warning: format(Buchanan, ) is not allowed: <wr:out select=’SELECT dbo.Employees.LastName FROM dbo.Employees’ type=‘NUMBER' nickname=TypeError’ error-handling= Ignore type error;Ignore formatting error;Iqnore select error;Node must exist’ datasource=’MSSQL’/>

warning: Could not parse: Adam: <wr:out select='/Formats-to-test/Author/Firstname’ type=‘DATE’ format=‘categary-date-type:0-format:m/d/yyyy’; nickname=’FORMAT_PROBLEM' error-handling=‘Ignore formatting error;Ignore select error’ datasource='TestingDatabase'/>

warning: format(Buchanan, ) is not allowed: <wr:out select=’SELECT dbo.Employees.LastName FROM dbo.Employees’ type=’NUMBER’ nickname=’TypeError’ error-handling=’Ignore type error;Ignore formatting error;Iqnore select error,Node must exist’ datasource=’MSSQL’/>

warning: Could not parse: Adam: <wr:out select='/Formats-to-test/Author/Firstname’ type=‘DATE’ format=‘categary-date-type:0-format:m/d/yyyy’; nickname=’FORMAT_PROBLEM' error-handling=‘Ignore formatting error;Ignore select error’ datasource='TestingDatabase'/>

Bad Select Statement#

warning: Invalid column name ‘dbo’. Final select: select dbo from dbo.Employees: <wr:out select=‘select dbo from dbo.Employees’ nickname=‘DNE1' error-handling=’Ignore select error’ datasource=‘MSSQL’/>

warning: Invalid column name ‘dbo’. Final select: select dbo from dbo.Employees: <wr:out select=‘select dbo from dbo.Employees’ nickname=‘DNE1' error-handling=’Ignore select error’ datasource=‘MSSQL’/>

Node Does Not Exist#

error: The tag returned no nodes: <wr:out select='/Formats-to-test/Nada’ nickname=‘Nadal' error-handling='Node must exist’ datasource=’TestingDatabase’/>

error: The tag returned no nodes: <wr:out select='/Formats-to-test/Nada’ nickname=‘Nadal' error-handling='Node must exist’ datasource=TestingDatabase’/>

Node Is Null#

warning: The tag is empty: <wr:out select=‘select ShipRegion from dbo.Orders where OrderID=10248’ nickname=‘[ShipRegion]’ error-handling=‘Node must not return NULL’ datasource=‘MSSQL’/>

warning: The tag is empty: <wr:out select=‘select ShipRegion from dbo.Orders where OrderID=10248’ nickname=‘[ShipRegion]’ error-handling=‘Node must not return NULL’ datasource=‘MSSQL’/>

Verification Issues#

warning: Tag uses undefined data source ‘OData’: <wr:set select=‘Employees?$select=Nada&amp;$top=1' var='varName3’ nickname=‘DNE8' error-handling=‘Ignore select error’ datasource='OData’/>

warning: Tag uses undefined data source ‘OData’: <wr:set select=‘Employees?$select=Nada&amp;$top=1' var='varName3’ nickname=‘DNE' error-handling=‘Ignore select error’ datasource='OData'/>

TrackErrors POST Request Node#

You enable error handling by adding the TrackErrors node to your POST request body. The node must be added within the “Template” node. Here are the valid TrackErrors values:

<TrackErrors>0</TrackErrors>  <!-- disables both verify and error handling -->
<TrackErrors>1</TrackErrors>  <!-- enables error handling only -->
<TrackErrors>2</TrackErrors>  <!-- enables verify only -->
<TrackErrors>3</TrackErrors>  <!-- enables both verify and error handling -->

Error Handling Results#

Error handling and verify results are returned within the <Errors> node at the end of the template's base64 output, with individual issues listed within individual <Issue> nodes, e.g.:

<Errors>
    <Issue>
        <Message>warning: ElementTable is off page 1 lower right edge at 16046,1410</Message></Issue><Issue><Message>warning: Picture 'Picture_2' is off page 1 anchored at -19,-19</Message>
    </Issue>
    <Issue>
        <Message>warning: Picture 'Picture_2' is off page 1 lower right edge at 15866,12236</Message>
    </Issue>
</Errors>

Example XML POST Request with Error Handling#

Here is an example XML POST request, with the <TrackErrors/> added:

<Template>
    <TrackErrors>3</TrackErrors> <!-- enables both verify and error handling -->
    <Uri>http://localhost:81/Templates/Manufacturing.docx</Uri>
    <OutputFormat>pdf</OutputFormat>
    <Datasources>
        <Datasource>
            <Name>MANF_DATA_2009</Name>
            <Type>xml</Type>
            <Uri>http://localhost:81/Data/Manufacturing.xml</Uri>
        </Datasource>
    </Datasources>
</Template>